doc: Switch documentation to gi-docgen

Part-of: <https://gitlab.gnome.org/GNOME/gnome-shell/-/merge_requests/1873>

diff --git a/docs/reference/meson.build b/docs/reference/meson.build
index 77d9fdee40f824f1a8eae8beddabc02a701aecc9..be92d0297a3c0bf99a717766f30c2e637ac0e529 100644 (file)
--- a/docs/reference/meson.build
+++ b/docs/reference/meson.build
@@ -1,5 +1,18 @@
-version_conf = configuration_data()
-version_conf.set('VERSION', meson.project_version())
+gidocgen = find_program('gi-docgen', required: get_option('gtk_doc'))
+
+doc_conf = configuration_data()
+doc_conf.set('MUTTER_API_VERSION', mutter_api_version)
+
+gi_docgen_common_args = [
+  '--quiet',
+  '--no-namespace-dir',
+]
+
+if get_option('werror')
+  gi_docgen_common_args += ['--fatal-warnings']
+endif
+
+docs_dir = datadir / 'doc'
 
 subdir('shell')
 subdir('st')

diff --git a/docs/reference/shell/meson.build b/docs/reference/shell/meson.build
index 96b0d087daf25a702ecf0117cf672a271de71758..4ea7069e5debe54bfe19cf4bfa1b1685c5ce7c84 100644 (file)
--- a/docs/reference/shell/meson.build
+++ b/docs/reference/shell/meson.build
@@ -1,51 +1,25 @@
-private_headers = [
-  'gactionmuxer.h',
-  'gactionobservable.h',
-  'gactionobserver.h',
-  'shell-network-agent.h',
-]
-
-exclude_directories = [
-  'calendar-server',
-  'hotplug-sniffer',
-  'st',
-  'tray'
-]
-
-ifaces = [
-  ['org.gnome.Shell.Screenshot', 'org.gnome.Shell.Screenshot.xml'],
-  ['org.gnome.ShellSearchProvider', 'org.gnome.Shell.SearchProvider.xml'],
-  ['org.gnome.ShellSearchProvider2', 'org.gnome.Shell.SearchProvider2.xml']
-]
-foreach iface : ifaces
-  custom_target(iface[0] + ' docs',
-    input: '../../../data/dbus-interfaces/@0@.xml'.format(iface[0]),
-    output: 'doc-gen-' + iface[1],
-    command: [
-      'gdbus-codegen',
-      '--interface-prefix=@0@.'.format(iface[0]),
-      '--generate-docbook', 'doc-gen',
-      '--output-directory', '@OUTDIR@',
-      '@INPUT@'
-    ],
-    build_by_default: true
-  )
-endforeach
-
-configure_file(
-  input: 'version.xml.in',
-  output: 'version.xml',
-  configuration: version_conf
+shell_toml = configure_file(
+  input: 'shell.toml.in',
+  output: 'shell.toml',
+  configuration: doc_conf
 )
 
-gnome.gtkdoc('shell',
-  main_sgml: 'shell-docs.sgml',
-  src_dir: [
-    join_paths(meson.project_source_root(), 'src'),
-    join_paths(meson.project_build_root(), 'src')
-  ],
-  scan_args: [
-    '--ignore-headers=' + ' '.join(private_headers + exclude_directories)
+custom_target('shell-doc',
+  input: [shell_toml, libshell_gir[0]],
+  output: 'shell',
+  command: [
+    gidocgen,
+    'generate',
+    gi_docgen_common_args,
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../src'),
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../src/st'),
+    '--add-include-path=@0@'.format(mutter_dep.get_variable('girdir')),
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../subprojects/gvc'),
+    '--config=@INPUT0@',
+    '--output-dir=@OUTPUT@',
+    '--content-dir=@0@'.format(meson.current_source_dir()),
+    '@INPUT1@',
   ],
-  install: true
+  install: true,
+  install_dir: docs_dir,
 )

diff --git a/docs/reference/shell/shell-docs.sgml b/docs/reference/shell/shell-docs.sgml
deleted file mode 100644 (file)
index 04255cd..0000000
--- a/docs/reference/shell/shell-docs.sgml
+++ /dev/null
@@ -1,67 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
-[
-  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
-  <!ENTITY version SYSTEM "version.xml">
-]>
-<book id="index">
-  <bookinfo>
-    <title>Shell Reference Manual</title>
-    <releaseinfo>
-      for Shell &version;.
-      <!--The latest version of this documentation can be found on-line at
-      <ulink role="online-location" url="http://[SERVER]/shell/index.html">http://[SERVER]/shell/</ulink>.-->
-    </releaseinfo>
-  </bookinfo>
-
-  <chapter>
-    <title>Actors</title>
-    <xi:include href="xml/shell-stack.xml"/>
-  </chapter>
-  <chapter>
-    <title>Application tracking</title>
-    <xi:include href="xml/shell-app.xml"/>
-    <xi:include href="xml/shell-app-usage.xml"/>
-    <xi:include href="xml/shell-window-tracker.xml"/>
-  </chapter>
-  <chapter>
-    <title>Search</title>
-    <xi:include href="xml/shell-app-system.xml"/>
-  </chapter>
-  <chapter>
-    <title>Tray Icons</title>
-    <xi:include href="xml/shell-tray-icon.xml"/>
-    <xi:include href="xml/shell-tray-manager.xml"/>
-  </chapter>
-  <chapter>
-    <title>Integration helpers and utilities</title>
-    <xi:include href="doc-gen-org.gnome.Shell.SearchProvider.xml"/>
-    <xi:include href="doc-gen-org.gnome.Shell.SearchProvider2.xml"/>
-    <xi:include href="xml/shell-global.xml"/>
-    <xi:include href="xml/shell-action-modes.xml"/>
-    <xi:include href="xml/shell-wm.xml"/>
-    <xi:include href="xml/shell-util.xml"/>
-    <xi:include href="xml/shell-mount-operation.xml"/>
-    <xi:include href="xml/shell-polkit-authentication-agent.xml"/>
-  </chapter>
-  <!-- FIXME:
-       Not generated at the moment, find out whether to blame gtk-doc or meson
-  -->
-  <!--
-  <chapter id="object-tree">
-    <title>Object Hierarchy</title>
-     <xi:include href="xml/tree_index.sgml"/>
-  </chapter>
-  -->
-  <index id="api-index-full">
-    <title>API Index</title>
-    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="deprecated-api-index" role="deprecated">
-    <title>Index of deprecated API</title>
-    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
-  </index>
-
-  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
-</book>

diff --git a/docs/reference/shell/shell.toml.in b/docs/reference/shell/shell.toml.in
new file mode 100644 (file)
index 0000000..565fc8d
--- /dev/null
+++ b/docs/reference/shell/shell.toml.in
@@ -0,0 +1,41 @@
+[library]
+namespace = "Shell"
+version = "@MUTTER_API_VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/gnome-shell/"
+repository_url = "https://gitlab.gnome.org/GNOME/gnome-shell.git"
+website_url = "https://www.gnome.org"
+license = "GPL-2.0-or-later"
+description = "Shell"
+dependencies = ["GObject-2.0", "Gio-2.0", "Meta-@MUTTER_API_VERSION@", "Clutter-@MUTTER_API_VERSION@"]
+devhelp = true
+search_index = true
+
+  [dependencies."GObject-2.0"]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://docs.gtk.org/gobject"
+
+  [dependencies."Gio-2.0"]
+  name = "Gio"
+  description = "GObject Interfaces and Objects, Networking, IPC, and I/O"
+  docs_url = "https://docs.gtk.org/gio"
+
+  [dependencies."Meta-@MUTTER_API_VERSION@"]
+  name = "Meta"
+  description = "The mutter display server, window manager and compositor library"
+  docs_url = "https://gnome.pages.gitlab.gnome.org/mutter/meta/"
+
+  [dependencies."Clutter-@MUTTER_API_VERSION@"]
+  name = "Clutter"
+  description = "An OpenGL based 'interactive canvas' library"
+  docs_url = "https://gnome.pages.gitlab.gnome.org/mutter/clutter/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/gnome-shell/-/blob/HEAD/"
+
+[extra]
+urlmap_file = "urlmap.js"

diff --git a/docs/reference/shell/urlmap.js b/docs/reference/shell/urlmap.js
new file mode 100644 (file)
index 0000000..85f05ec
--- /dev/null
+++ b/docs/reference/shell/urlmap.js
@@ -0,0 +1,11 @@
+baseURLs = [
+    [ 'GLib', 'https://docs.gtk.org/glib/' ],
+    [ 'GObject', 'https://docs.gtk.org/gobject/' ],
+    [ 'Gio', 'https://docs.gtk.org/gio/' ],
+    [ 'GdkPixbuf', 'https://docs.gtk.org/gdk-pixbuf/' ],
+    [ 'Meta', 'https://gnome.pages.gitlab.gnome.org/mutter/meta/' ],
+    [ 'Mtk', 'https://gnome.pages.gitlab.gnome.org/mutter/mtk/' ],
+    [ 'Cogl', 'https://gnome.pages.gitlab.gnome.org/mutter/cogl/' ],
+    [ 'Clutter', 'https://gnome.pages.gitlab.gnome.org/mutter/clutter/' ],
+    [ 'St', 'https://gnome.pages/gitlab.gnome.org/gnome-shell/st/' ],
+]

diff --git a/docs/reference/shell/version.xml.in b/docs/reference/shell/version.xml.in
deleted file mode 100644 (file)
index d78bda9..0000000
--- a/docs/reference/shell/version.xml.in
+++ /dev/null
@@ -1 +0,0 @@
-@VERSION@

diff --git a/docs/reference/st/meson.build b/docs/reference/st/meson.build
index 0c4b4207b0ea22409125802edb439e0f3a80355a..ad63a945664272241f3e72711b4e3d3f7807d9c3 100644 (file)
--- a/docs/reference/st/meson.build
+++ b/docs/reference/st/meson.build
@@ -1,23 +1,24 @@
-private_headers = [
-  'st-private.h',
-  'st-theme-node-private.h'
-]
-
-configure_file(
-  input: 'version.xml.in',
-  output: 'version.xml',
-  configuration: version_conf
+st_toml = configure_file(
+  input: 'st.toml.in',
+  output: 'st.toml',
+  configuration: doc_conf
 )
 
-gnome.gtkdoc('st',
-  main_sgml: 'st-docs.sgml',
-  src_dir: [
-    join_paths(meson.project_source_root(), 'src', 'st'),
-    join_paths(meson.project_build_root(), 'src', 'st')
-  ],
-  scan_args: [
-    '--ignore-headers=' + ' '.join(private_headers),
-    '--rebuild-sections'
+custom_target('st-doc',
+  input: [st_toml, libst_gir[0]],
+  output: 'st',
+  command: [
+    gidocgen,
+    'generate',
+    gi_docgen_common_args,
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../src'),
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../src/st'),
+    '--add-include-path=@0@'.format(mutter_dep.get_variable('girdir')),
+    '--config=@INPUT0@',
+    '--output-dir=@OUTPUT@',
+    '--content-dir=@0@'.format(meson.current_source_dir()),
+    '@INPUT1@',
   ],
-  install: true
+  install: true,
+  install_dir: docs_dir,
 )

diff --git a/docs/reference/st/st-docs.sgml b/docs/reference/st/st-docs.sgml
deleted file mode 100644 (file)
index 4e5fd99..0000000
--- a/docs/reference/st/st-docs.sgml
+++ /dev/null
@@ -1,69 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
-[
-  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
-  <!ENTITY version SYSTEM "version.xml">
-]>
-<book id="index">
-  <bookinfo>
-    <title>St Reference Manual</title>
-    <releaseinfo>
-      for St &version;.
-      <!--The latest version of this documentation can be found on-line at
-      <ulink role="online-location" url="http://[SERVER]/st/index.html">http://[SERVER]/st/</ulink>.-->
-    </releaseinfo>
-  </bookinfo>
-
-  <part>
-    <title>API reference</title>
-    <chapter id="base">
-      <title>Abstract classes and Interfaces</title>
-      <xi:include href="xml/st-widget.xml"/>
-      <xi:include href="xml/st-widget-accessible.xml"/>
-      <xi:include href="xml/st-scrollable.xml"/>
-    </chapter>
-    <chapter id="widgets">
-      <title>Widgets</title>
-      <xi:include href="xml/st-button.xml"/>
-      <xi:include href="xml/st-drawing-area.xml"/>
-      <xi:include href="xml/st-entry.xml"/>
-      <xi:include href="xml/st-icon.xml"/>
-      <xi:include href="xml/st-label.xml"/>
-    </chapter>
-    <chapter id="containers">
-      <title>Containers</title>
-      <xi:include href="xml/st-bin.xml"/>
-      <xi:include href="xml/st-box-layout.xml"/>
-      <xi:include href="xml/st-scroll-view.xml"/>
-    </chapter>
-
-    <chapter id="styling">
-      <title>Styling</title>
-      <xi:include href="xml/st-theme.xml"/>
-      <xi:include href="xml/st-theme-context.xml"/>
-      <xi:include href="xml/st-theme-node.xml"/>
-      <xi:include href="xml/st-theme-node-transition.xml"/>
-      <xi:include href="xml/st-texture-cache.xml"/>
-    </chapter>
-  </part>
-  <!-- FIXME:
-       Not generated at the moment, find out whether to blame gtk-doc or meson
-  -->
-  <!--
-  <chapter id="object-tree">
-    <title>Object Hierarchy</title>
-     <xi:include href="xml/tree_index.sgml"/>
-  </chapter>
-  -->
-  <index id="api-index-full">
-    <title>API Index</title>
-    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="deprecated-api-index" role="deprecated">
-    <title>Index of deprecated API</title>
-    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
-  </index>
-
-  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
-</book>

diff --git a/docs/reference/st/st.toml.in b/docs/reference/st/st.toml.in
new file mode 100644 (file)
index 0000000..c1f35c7
--- /dev/null
+++ b/docs/reference/st/st.toml.in
@@ -0,0 +1,36 @@
+[library]
+namespace = "St"
+version = "@MUTTER_API_VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/gnome-shell/"
+repository_url = "https://gitlab.gnome.org/GNOME/gnome-shell.git"
+website_url = "https://www.gnome.org"
+license = "LGPL-2.0-or-later"
+description = "Shell Toolkit"
+dependencies = ["GObject-2.0", "Gio-2.0", "Clutter-@MUTTER_API_VERSION@"]
+devhelp = true
+search_index = true
+
+  [dependencies."GObject-2.0"]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://docs.gtk.org/gobject"
+
+  [dependencies."Gio-2.0"]
+  name = "Gio"
+  description = "GObject Interfaces and Objects, Networking, IPC, and I/O"
+  docs_url = "https://docs.gtk.org/gio"
+
+  [dependencies."Clutter-@MUTTER_API_VERSION@"]
+  name = "Clutter"
+  description = "An OpenGL based 'interactive canvas' library"
+  docs_url = "https://gnome.pages.gitlab.gnome.org/mutter/clutter/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/gnome-shell/-/blob/HEAD/"
+
+[extra]
+urlmap_file = "urlmap.js"

diff --git a/docs/reference/st/urlmap.js b/docs/reference/st/urlmap.js
new file mode 100644 (file)
index 0000000..eed228a
--- /dev/null
+++ b/docs/reference/st/urlmap.js
@@ -0,0 +1,10 @@
+baseURLs = [
+    [ 'GLib', 'https://docs.gtk.org/glib/' ],
+    [ 'GObject', 'https://docs.gtk.org/gobject/' ],
+    [ 'Gio', 'https://docs.gtk.org/gio/' ],
+    [ 'Pango', 'https://docs.gtk.org/pango/' ],
+    [ 'GdkPixbuf', 'https://docs.gtk.org/gdk-pixbuf/' ],
+    [ 'Clutter', 'https://gnome.pages.gitlab.gnome.org/mutter/clutter/' ],
+    [ 'Cogl', 'https://gnome.pages.gitlab.gnome.org/mutter/cogl/' ],
+    [ 'Meta', 'https://gnome.pages.gitlab.gnome.org/mutter/meta/' ],
+]

diff --git a/docs/reference/st/version.xml.in b/docs/reference/st/version.xml.in
deleted file mode 100644 (file)
index d78bda9..0000000
--- a/docs/reference/st/version.xml.in
+++ /dev/null
@@ -1 +0,0 @@
-@VERSION@

diff --git a/meson.build b/meson.build
index 70ba7110697e65c52a1c36a0ea388f16ae7b5ded..e550dd91a99e3f2a7873b5719d9523d4c82a7658 100644 (file)
--- a/meson.build
+++ b/meson.build
@@ -95,6 +95,11 @@ x11_dep = dependency('x11')
 schemas_dep = dependency('gsettings-desktop-schemas', version: schemas_req)
 gnome_desktop_dep = dependency('gnome-desktop-4', version: gnome_desktop_req)
 
+gidocgen_dep = dependency('gi-docgen',
+  version: '>= 2021.1',
+  fallback: ['gi-docgen', 'dummy_dep'],
+  required: get_option('gtk_doc'))
+
 nm_deps = []
 if get_option('networkmanager')
   nm_deps += dependency('libnm', version: nm_req)

diff --git a/src/meson.build b/src/meson.build
index 070312bd0cdf397068855989d36250e876752de3..748d855a39a6b23e53d3913574b0579e033c5584 100644 (file)
--- a/src/meson.build
+++ b/src/meson.build
@@ -231,7 +231,7 @@ libshell_gir_includes += [
   libst_gir[0]
 ]
 
-gnome.generate_gir(libshell,
+libshell_gir = gnome.generate_gir(libshell,
   sources: libshell_gir_sources,
   nsversion: mutter_api_version,
   namespace: 'Shell',

diff --git a/subprojects/gi-docgen.wrap b/subprojects/gi-docgen.wrap
new file mode 100644 (file)
index 0000000..98cd921
--- /dev/null
+++ b/subprojects/gi-docgen.wrap
@@ -0,0 +1,6 @@
+[wrap-git]
+directory=gi-docgen
+url=https://gitlab.gnome.org/GNOME/gi-docgen.git
+push-url=ssh://git@gitlab.gnome.org:GNOME/gi-docgen.git
+revision=main
+depth=1